home *** CD-ROM | disk | FTP | other *** search
/ Scene Storm / Scene Storm - Volume 1.iso / coding / c / snoopdos_source / snoopdos.roadmap < prev    next >
Text File  |  1996-02-16  |  18KB  |  385 lines
  1.  
  2.                         SnoopDos 3.0 -- Source Code Roadmap
  3.  
  4.            Copyright © Eddy Carroll, September 1994. Freely distributable.
  5.  
  6.  
  7. INTRODUCTION
  8.  
  9.     SnoopDos was written using SAS/C 6.51. The Amiga programming community
  10.     owe a large debt of thanks to Doug Walker, Steve Krueger, Jim Cooper,
  11.     and everyone else at SAS Institute for providing such a useful and
  12.     stable development environment. Without SAS/C, development of SnoopDos
  13.     would have taken significantly longer.
  14.  
  15.     If you have SAS/C, then you should be able to recompile SnoopDos with
  16.     no problems by simply typing "smake" in this directory. You might want
  17.     to turn off optimisation in the SCOPTIONS file if you are experimenting;
  18.     otherwise, prepare for a long wait.
  19.  
  20.     If you are using DICE or another compiler, you will need to ensure that
  21.     you are using similar compiler options to those listed in SCOPTIONS. You
  22.     will also need to change the function prototypes in patches.h and perhaps
  23.     in patches.c. A future release may detect DICE automatically and do the
  24.     right thing.
  25.  
  26.     In general, most files have an initialisation function and all have a
  27.     cleanup function. The initialisation function should be called at the
  28.     beginning of the code and the cleanup function at the end. All cleanup
  29.     functions are safe to call multiple times if necessary.
  30.  
  31.     Note that all the source code has been formatted with a tab setting of
  32.     4 spaces. If your editor uses tabs set to some other width, then it is
  33.     strongly recommended that you run the code through Detab or a similar
  34.     utility, otherwise it will look a mess.
  35.  
  36.  
  37. MODULE OVERVIEW
  38. ---------------
  39. Here's a summary of the different files and what they are used for:
  40.  
  41.        system.h   Master include file for all system headers
  42.        system.c   Includes system.h -- used to create the GST file
  43.      snoopdos.h   Defines all program globals, structures, constants, protos
  44.      snoopdos.c   Top level module. Initialises and cleans up other modules
  45.        buffer.c   Allocates and formats events in the event buffer
  46.      language.c   Makes localised text strings available to other modules
  47.     snooptext.h   Master message include file used by all modules
  48.       patches.c   All the patch code inserted into system libraries
  49.       patches.h   Header file that prototypes all the patched functions
  50.     patchcode.s   Low-level assembly code used by patch mechanism
  51.      settings.c   Handles the command line interface to SnoopDos
  52.           gui.h   Constants which define the exact appearance of the GUI
  53.       mainwin.c   All functions relating to the main window
  54.        subwin.c   All functions relating to the other three windows
  55.       miscwin.c   Miscellaneous window and screen functions used everywhere
  56.        hotkey.c   Handles commodity interface + Workbench AppIcon/Toolmenu
  57.          icon.h   Image data for custom SnoopDos icon (from IconEdit)
  58.     snooptext.cd  SnoopDos catalog description file, for localisation
  59.     snooptext.ct  Example SnoopDos translation file, for localisation
  60.     testcalls.c   Separate utility to stress test the SnoopDos patch code.
  61.  
  62.  
  63. MODULE GUIDE
  64. ------------
  65. Here's a more detailed look at the contents of each module. See the module
  66. itself for full details.
  67.  
  68.  
  69. SYSTEM.H
  70. SYSTEM.C
  71.  
  72.     System.h is the master include file for all Amiga system includes. Any
  73.     system include used by any module is placed in here. The entire set of
  74.     includes is then precompiled into a SAS/C GST file, which greatly speeds
  75.     up compilation.
  76.  
  77.     System.c is the file used to generate the GST -- it simply includes
  78.     the System.h header file.
  79.  
  80.  
  81. SNOOPDOS.H
  82.  
  83.     SnoopDos.h is included by all other modules. It defines all the global
  84.     variables, structures, and prototypes used by SnoopDos. It also includes
  85.     the default program settings. Global variables with initial values are
  86.     defined when this file is included by SnoopDos.c, and declared when it's
  87.     included by other modules. Thus, if you change the initial value of
  88.     any global variables, SnoopDos.c must be recompiled (the makefile does
  89.     this automatically).
  90.  
  91.  
  92. SNOOPDOS.C
  93.  
  94.     SnoopDos.c is the top level module. It opens all the necessary libraries,
  95.     and calls the initialisation routines of most of the other modules. It is
  96.     also responsible for keeping the global program settings up to date. The
  97.     most important functions are:
  98.  
  99.               Cleanup()  Calls cleanup function of each module and exits
  100.              OpenLibs()  Opens all libraries needed by SnoopDos
  101.             mysprintf()  Re-entrant version of sprintf() library function
  102.       InstallSettings()  Updates subset of global settings with new values
  103.              MainLoop()  Waits for incoming events and dispatches them
  104.                  main()  Entry point for whole program.
  105.  
  106.  
  107. BUFFER.C
  108.  
  109.     Buffer.c contains all the functions that deal directly with the SnoopDos
  110.     event buffer. An "event" contains all the information needed to create a
  111.     single line of output in the SnoopDos window. Here are the most important
  112.     functions:
  113.     
  114.               InitBuffer()  Must be called at start of program
  115.           CleanupBuffers()  Called when program exits
  116.       SetTotalBufferSize()  Changes buffer size (allocating one if needed)
  117.              ClearBuffer()  Empties buffer contents
  118.              GetNewEvent()  Allocates space for a new event
  119.        ParseFormatString()  Converts "%d %s %p" into an internal format
  120.        BuildFormatString()  Converts internal format back to ascii string
  121.              FormatEvent()  Creates a formatted output line from an event
  122.          UnderlineTitles()  Creates an underline string for current titles
  123.          CheckSegTracker()  Called regularly to see if SegTracker is loaded
  124.  
  125.  
  126. LANGUAGE.C
  127. SNOOPTEXT.H
  128.  
  129.     Language.c deals with all the text strings used by SnoopDos. Specifically,
  130.     it identifies the users locale and decides whether to use the strings
  131.     hard-coded in the executable, or to read them from an external catalog
  132.     file instead. The main functions are:
  133.  
  134.         InitTextTable()  Called first. Creates default (english) string table
  135.            InitLocale()  Checks for external catalog files
  136.         CleanupLocale()  Frees any resources used by localisation
  137.  
  138.     Snooptext.h is generated automatically from SnoopText.cd by Commodore's
  139.     CATCOMP utility. It defines a unique numeric identifier for each string,
  140.     and (when included by language.c) the strings themselves. It should never
  141.     be edited by hand. It's included in the archive for the convenience of
  142.     those who don't have CatComp.
  143.  
  144.  
  145. PATCHES.C
  146. PATCHES.H
  147. PATCHCODE.S
  148.  
  149.     Patches.c is the backbone of SnoopDos -- it contains all the patch
  150.     routines that intercept calls made by other programs to various system
  151.     functions. Most of the functions in this file must be completely
  152.     re-entrant, since they can be called by many processes simultaneously.
  153.     The most important functions are:
  154.  
  155.             InitPatches()  Initialises the memory-resident patch code
  156.           UpdatePatches()  Attempts to install or remove all patches as needed
  157.        LoadFuncSettings()  Updates patches to reflect function settings
  158.          CleanupPatches()  Removes all patches (waiting until it's safe)
  159.        UpdateDeviceList()  Builds list of currently mounted DOS devices
  160.         InitRamLibPatch()  Fixes a bug in ramlib that can crash SnoopDos
  161.      BackgroundProcCode()  Background task for pattern matching/name expansion
  162.              SetPattern()  Parses the current AmigaDOS task match pattern
  163.         CreateEvent()  Creates a new event, filling in various fields
  164.        HandlePaused()  Puts a task to sleep when Pause is enabled
  165.        JumpOrigFunc()  A macro that exits by calling the original function
  166.  
  167.     Patches.h contains the prototypes for all the functions that are patched.
  168.     Each prototype defines the registers passed, along with a base register
  169.     in A6. The LVO offsets for each function are also defined here.
  170.  
  171.     Patchcode.s contains the low-level assembly language patch code which is
  172.     used for each function. The same piece of code is copied multiple times
  173.     to create a unique patch for each function. Whenever any changes are
  174.     made to this code, or to the Patch structure which contains the code and
  175.     associated data, then the corresponding structure in Patches.c must be
  176.     updated. In addition, if the stack alignment on entry to the C patches
  177.     changes, the JumpOrigFunc() and MarkCallAddr macros must be adjusted.
  178.  
  179.  
  180. SETTINGS.C
  181.  
  182.     Settings.c controls all the program settings. This includes loading and
  183.     saving settings files to disk, parsing the Workbench and CLI startup
  184.     options, and handling the ARexx interface. The important functions are:
  185.  
  186.          InitSettings()  Initialises command name table
  187.          ParseCommand()  Syntax checks a SnoopDos command line
  188.           ExecCommand()  Executes a SnoopDos command line
  189.            SaveConfig()  Writes current settings to a command file
  190.            LoadConfig()  Executes all the commands in a command file
  191.            SendRemote()  Sends a command to a background copy of SnoopDos
  192.          ShowCommands()  Prints a formatted list of SnoopDos commands
  193.      ParseStartupOpts()  Parses Workbench and CLI startup options
  194.  
  195.          InitRexxPort()  Initialises ARexx port
  196.       CleanupRexxPort()  Frees ARexx port
  197.        HandleRexxMsgs()  Handles incoming ARexx messages
  198.  
  199.  
  200. GUI.H
  201.  
  202.     Gui.h file defines constants which relate to the SnoopDos GUI. These
  203.     are mainly used to finetune the gadget layout but also include a few
  204.     keyboard-related definitions. This file is included by MAINWIN.C,
  205.     SUBWIN.C and MISCWIN.C
  206.  
  207.  
  208. MAINWIN.C
  209.  
  210.     Mainwin.c handles everything associated with the main window. It has
  211.     grown too large and should really be subdivided (again). Here are the
  212.     most important functions in the file:
  213.  
  214.           CheckForScreen()  Locates current screen (locking if necessary)
  215.             ShowSnoopDos()  Opens SnoopDos window on the current screen
  216.             HideSnoopDos()  Closes main window, help and any other windows
  217.           OpenMainWindow()  Opens main window
  218.      CreateScrollGadgets()  Creates BOOPSI scroll gadgets for main window
  219.        CreateMainGadgets()  Creates gadtools gadgets for main window
  220.          CloseMainWindow()  Closes main window
  221.        CleanupMainWindow()  Frees all resources for main window
  222.         ReOpenMainWindow()  Closes and then opens main window
  223.        RecordWindowSizes()  Records sizes of all open windows
  224.         SetMainHideState()  Enables/disables Hide gadget and window title
  225.  
  226.                InitMenus()  Initialises shortcut keys for localised menus
  227.           SetMenuOptions()  Updates boolean menu options with current settings
  228.           HandleMainMsgs()  Handles menu, gadget and keypress input
  229.          HandleNewEvents()  Outputs any new events to the main window
  230.           SetMonitorMode()  Sets monitor mode to normal, Paused or Disabled
  231.  
  232.         RedrawMainWindow()  Draws everything in main window except gadgets
  233.           DrawHeaderLine()  Draws headerline at top of screen
  234.               ShowBuffer()  Redraws the main window buffer
  235.         DrawSelectedLine()  Highlights a single line in the buffer
  236.        ClearWindowBuffer()  Erases window buffer display
  237.         ScrollHorizontal()  Efficiently scrolls window contents to left/right
  238.        UpdateMainHScroll()  Updates horizontal scroll gadget to current offset
  239.        UpdateMainVScroll()  Updates vertical scroll gadget to current position
  240.               ShowStatus()  Displays a message in the status bar
  241.             UpdateStatus()  Displays status message reflecting current state
  242.  
  243.                  OpenLog()  Opens a new logfile
  244.                 WriteLog()  Writes some text to the logfile
  245.                 CloseLog()  Closes the current logfile
  246.               SaveBuffer()  Saves current buffer contents to file/clipboard
  247.             SetLogGadget()  Selects appropriate wording for log gadget
  248.  
  249. SUBWIN.C
  250.  
  251.     Subwin.c contains all the functions needed to manage the format editor,
  252.     settings window and function window. The most important functions are:
  253.  
  254.           CleanupSubWindow()  Closes all currently open windows
  255.  
  256.         OpenSettingsWindow()  Opens settings window 
  257.        CloseSettingsWindow()  Closes the settings window
  258.      CreateSettingsGadgets()  Creates font-sensitive gadgets for window
  259.         HandleSettingsMsgs()  Handles keyboard and gadget input
  260.  
  261.         OpenFunctionWindow()  Opens function window and creates gagdets
  262.      CreateFunctionGadgets()  Creates font-sensitive gadgets for window
  263.        CloseFunctionWindow()  Closes the functions window
  264.             HandleFuncMsgs()  Handles keyboard and gadget input
  265.        ResetFuncToSelected()  Handles the "All/None/Selected" function gadgets
  266.               ShowFuncOpts()  Updates display of current function settings
  267.                GetFuncName()  Returns a name matching a function ID
  268.  
  269.           OpenFormatWindow()  Creates the format editor window and gadgets
  270.          CloseFormatWindow()  Closes the format editor window
  271.        CreateFormatGadgets()  Creates font-sensitive gadgets for window
  272.           HandleFormatMsgs()  Handles gadget and keyboard input
  273.       InstallNewFormat()  Updates all windows to reflect a new format
  274.              CreateBob()  Creates a new BOB (Blitter OBject)
  275.            FreeBob()  Frees a BOB created earlier
  276.                  PickupBob()  Copies a text line into a BOB for Drag & Drop
  277.            DropBob()  Drops the text line in a new position
  278.          UpdateBob()  Moves BOB to a new osition
  279.  
  280. MISCWIN.C
  281.  
  282.     Miscwin.c contains a variety of functions related to the GUI that don't
  283.     conveniently fit anywhere else. As well as general screen and window
  284.     functions, it also handles the AmigaGuide interface, and creates the
  285.     custom images used for the file/font gadgets in the settings window.
  286.  
  287.                 InitFonts()  Initialises fonts according to system preferences
  288.               SetupScreen()  Locates a screen for SnoopDos to open on
  289.             CleanupScreen()  Frees misc info related to current screen
  290.                 ShowError()  Displays an error requester
  291.               GetResponse()  Displays a requester with multiple choices
  292.                SelectFont()  Displays ASL font requester to get a font
  293.                SelectFile()  Displays ASL file requester to get a file name
  294.            AddKeyShortcut()  Update keyboard shortcuts array for a window
  295.                MyOpenFont()  Tries to open a font, from disk or from ROM 
  296.         ConvertIMsgToChar()  Converts an IntuiMsg RAWKEY event to ascii
  297.  
  298.                ShowAGuide()  Loads AmigaGuide and displays a help page
  299.             CleanupAGuide()  Shuts down AmigaGuide
  300.          HandleAGuideMsgs()  Handles incoming messages from AmigaGuide
  301.  
  302.         CreateCustomImage()  Creates a new scaled file or font image
  303.           FreeCustomImage()  Frees an image allocated earlier
  304.                ShowGadget()  Presses or releases a button gadget
  305.  
  306.  
  307. HOTKEY.C
  308. ICON.H
  309.  
  310.     Hotkey.c contains functions to handle commodity support, and interfacing
  311.     with Workbench (for AppIcon and ToolMenu support). It also deals with
  312.     icons. The important functions are:
  313.  
  314.            InstallHotKey()  Installs commodity hotkey, initialising if needed
  315.            CleanupHotKey()  Shuts down commodity exchange support
  316.         HandleHotKeyMsgs()  Handles incoming msgs from commodity exchange
  317.  
  318.           GetProgramIcon()  Finds (or creates) the SnoopDos program icon
  319.                WriteIcon()  Writes current icon to disk
  320.             CleanupIcons()  Frees any icons allocated earlier
  321.  
  322.          AddProgramToWorkbench()  Creates an AppIcon or Tools menu entry
  323.     RemoveProgramFromWorkbench()  Removes any outstanding appicons/menu items
  324.            HandleWorkbenchMsgs()  Handles incoming msgs from Workbench
  325.  
  326.     Icon.h contains the image data for the image used when writing icons to
  327.     disk if no icon could be found for the SnoopDos executable. This is
  328.     generated directly from IconEdit (set the SRC=YES tooltype), and has a
  329.     30 line header that does a few #define's to isolate IconEdit-dependent
  330.     variable names from the rest of the program.
  331.  
  332.  
  333. SNOOPTEXT.CD
  334. SNOOPTEXT.CT
  335.  
  336.     SnoopText.cd is the localisation file for SnoopDos. It contains all the
  337.     messages used throughout the program. This file is compiled by Commodore's
  338.     CatComp utility to provide SNOOPTEXT.H which is then included by all
  339.     other modules. Thus, modifying SnoopText.cd requires that everything be
  340.     recompiled from scratch.
  341.  
  342.     SnoopText.ct is a ready-to-go translation file which can be used with
  343.     CatComp to produce an external catalog file for use with SnoopDos. It
  344.     was generated automatically from SnoopText.cd using CatEdit by Rafael
  345.     D'Halleweyn and is included for the convenience of those who don't have
  346.     CatEdit to hand.
  347.  
  348.  
  349. TESTCALLS.C
  350.  
  351.     This is a completely separate program. It was written to provide a means
  352.     of stress testing SnoopDos. It is not complete, hence it is not part
  353.     of the main SnoopDos program archive. Currently, it supports all of the
  354.     system functions and a few DOS functions.
  355.  
  356.     It can be instructed to continuously call one or more of the functions
  357.     monitored by SnoopDos. Many subtle bugs were uncovered by running this
  358.     multiple times simultaneously.
  359.  
  360.  
  361. DISTRIBUTION CONDITIONS
  362. -----------------------
  363.  
  364. You may freely use portions of the SnoopDos source code in your own programs
  365. if you wish. However, if you use two or more complete functions from the
  366. SnoopDos code, you must acknowledge the origin of those functions in your
  367. documentation and source code.
  368.  
  369. You may modify the SnoopDos source code to create new versions of SnoopDos
  370. for your own use only. You may not redistribute such new versions without my
  371. explicit permission.
  372.  
  373.  
  374. FURTHER INFORMATION
  375. -------------------
  376. For additional information about the source code or algorithms used, you
  377. can contact me at:
  378.  
  379.     ecarroll@maths.tcd.ie
  380.     ecarroll@cix.compulink.co.uk
  381.  
  382. To obtain a copy of my PGP public key (used to authenticate distribution
  383. copies of SnoopDos 3.0 and above) send a message to ecarroll@maths.tcd.ie
  384. with the subject line "PGPKEY".
  385.